## -*- mode: html; coding: utf-8; -*-

## This file is part of CDS Invenio.
## Copyright (C) 2002, 2003, 2004, 2005, 2006, 2007, 2008 CERN.
##
## CDS Invenio is free software; you can redistribute it and/or
## modify it under the terms of the GNU General Public License as
## published by the Free Software Foundation; either version 2 of the
## License, or (at your option) any later version.
##
## CDS Invenio is distributed in the hope that it will be useful, but
## WITHOUT ANY WARRANTY; without even the implied warranty of
## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
## General Public License for more details.
##
## You should have received a copy of the GNU General Public License
## along with CDS Invenio; if not, write to the Free Software Foundation, Inc.,
## 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA.

<!-- WebDoc-Page-Title: FCKeditor Integration -->
<!-- WebDoc-Page-Navtrail: <a class="navtrail" href="<CFG_SITE_URL>/help/hacking">Hacking CDS Invenio</a> -->
<!-- WebDoc-Page-Revision: $Id$ -->

<h2>Contents</h2>

<ul style="list-style-type:None">
<li><strong>1. <a href="#1.">About FCKeditor</a></strong></li>
<li><strong>2. <a href="#2.">Maintenance</a></strong>
    <ul style="list-style-type:None">
    <li>2.1&nbsp;&nbsp;<a href="#2.1">Installation</a></li>
    <li>2.2&nbsp;&nbsp;<a href="#2.2">Upgrade</a></li>
    <li>2.3&nbsp;&nbsp;<a href="#2.3">Configuration</a></li>
    <li>2.4&nbsp;&nbsp;<a href="#2.4">Javscript vs Python Integration</a></li>
    </ul>
</li>
<li><strong>3. <a href="#3.">APIs</a></strong>
    <ul style="list-style-type:None">
    <li>3.1&nbsp;&nbsp;<a href="#3.1">Basic Integration</a></li>
    <li>3.2&nbsp;&nbsp;<a href="#3.2">File Upload Support</a></li>
    </ul>
</li>
</ul>

<p>This documentation is <strong>developer-oriented</strong>, and
provides maintenance information about the FCKeditor integration with
CDS Invenio. <br />
Read the CDS Invenio INSTALL file to learn how to install FCKeditor on
your CDS Invenio instance.</p>

<p>Also note that a major revision of FCKeditor is planned for version
3 (as well as a renaming to "CKEditor"). As a consequence, links from
this page to the FCKeditor documentation might be broken or outdated,
and the integration might need to be reworked. This documentation
should help in this respect.</p>

<h2><a name="1.">1. About FCKeditor</a></h2>

<p><a href="http://www.fckeditor.net/">FCKeditor</a> is a GPL WYSWYG
javascript-based HTML editor. It is currently used in the following
modules of CDS Invenio:</p>

<ul>

<li>WebComment: HTML-formatted comments/reviews, and file
attachment.</li>

</ul>

<p>It can optionally (and rather easily) be integrated into WebSubmit
Response Elements too, but there is no WebSubmit Core Element using
FCKeditor for the moment.</p>


<h2><a name="2.">Maintenance</a></h2>
<h3><a name="2.1">Installation</a></h3>
<p>Read the CDS Invenio INSTALL file to learn <em>how</em> to deploy FCKeditor on your installation.</p>

The <code>cds-invenio/Makefile.am::install-fckeditor-plugin</code> installs the necessary files
for the user:

<ul>

<li><strong>Editor:</strong> The editor itself and all the necessary
files (HTML and Javascript) are installed in
<code>/opt/cds-invenio/var/www/fckeditor/</code></li>

<li><strong>Server-side integration:</strong> the class to embed the
editor using Python (instead of Javascript) goes here:
<code>/opt/cds-invenio/lib/python/invenio/fckeditor/fckeditor.py</code>
</li>

<li><strong>Server-side connector:</strong> the base Python classes
for the server-side connection (to support files upload/browsing) are
copied into
<code>/opt/cds-invenio/lib/python/invenio/fckeditor/editor/filemanager/connectors/py/</code>,
keeping the source hierarchy of directories</li>

</ul>

<p>Usually, only the necessary files are copied (<a href="http://docs.fckeditor.net/FCKeditor_2.x/Developers_Guide/Deployment">Check which files need to be deployed</a>) and none are modified.</p>

Additional files from CDS Invenio are needed to support the editor
(these files might already be installed): <ul>

<li><strong><code>cds-invenio/modules/webstyle/etc/invenio-fckeditor-config.js</code>:</strong>
custom configuration file. Installed in
<code>/opt/cds-invenio/var/www/fckeditor/</code>.</li>

<li><strong><code>cds-invenio/modules/miscutil/lib/htmlutils.py</code>:</strong>
contains function <code>get_html_text_editor(..)</code> to wrap the
initialization of the editor. Should one change the way the editor is
integrated, this function only would need to be changed. This file is
always installed, even if "<code>make install-fckeditor-plugin</code>"
has never run.</li>

<li><strong><code>cds-invenio/modules/webstyle/lib/fckeditor_invenio_connector.py</code>:</strong>
subclasses the fckeditor connector for server-side integration, to
support files upload. This file is always installed, even if
"<code>make install-fckeditor-plugin</code>" has not never run.</li>
</ul>

<h3><a name="2.2">Upgrade</a></h3>

<p>Since the integration modifies no file of the editor, it should be
straightforward to upgrade to a newer version of the editor,
especially with minor revisions.</p>

<p>First check the FCKeditor release note, and read tips
 <a href="http://docs.fckeditor.net/FCKeditor_2.x/Developers_Guide/Installation/Upgrading">how to upgrade the editor</a>
 to ensure that the way <code>cds-invenio/Makefile.am</code> installs
the files is ok.</p>

<p>The easiest to test an upgrade is to increase the version number in
<code>cds-invenio/Makefile.am</code>, variable <code>FCKV</code> and run
"<code>Make install</code>". Make sure that the archive can still be
downloaded from the usual URL.</p>

<p>What should be specifically checked are
<code>htmlutils.get_html_text_editor(..)</code>,
<code>cds-invenio/modules/webstyle/etc/invenio-fckeditor-config.js</code> and
 <code>cds-invenio/modules/webstyle/lib/fckeditor_invenio_connector.py</code>:
they are basically the only files that interface with the FCKeditor,
and must adapt to modifications of FCKeditor APIs.</p>

<h3><a name="2.3">Configuration</a></h3>

<p>The configuration of FCKeditor (colors, size, behaviour) can be
done when instantiating the editor ("inline", in
<code>htmlutils.get_html_text_editor(..)</code> function) or via a
Javascript config file placed in a web accessible location. Read
FCKeditor documentation to learn more about these options.<br/>

The current solution is to have a maximum of the configuration made in
<code>htmlutils.get_html_text_editor(..)</code>, such that it is easy
to customize the editor directly from the source code, without having
to change any Javascript config file.</p>

<p>For the moment a single Javascript file
(<code>invenio-fckeditor-config.js</code>) is used, mainly to define
the toolbar sets, that cannot be defined "inline".</p>

<p><strong>It is to be thought if it would not be better to have the
configuration for each call of the function (or each CDS Invenio
module) in different config files. That would make the customization
of each instance possible by admin users.</strong></p>

<h3><a name="2.4">Javscript vs Python Integration</a></h3>

<p>FCKeditor can be integrated into pages either via Javascript, or
using the Python wrapper. The current way of doing is to use the
Python wrapper.</p>
<strong>Pro and cons of using the Python wrapper:</strong>

<ul style="list-style-type:none;">

<li><strong>+</strong> easier to read and maintain</li>
<li><strong>+</strong> can be pylinted</li>
<li><strong>+</strong> faster on client-side?</li>
<li><strong>+</strong> can partly hide changes in FCKeditor APIs?</li>
<li><strong>-</strong> cannot check if client has enabled Javascript
     (can only check
      user-agent for compatibility)<strong><a href="#aboutCheckingClientJavascript">*</a></strong></li>
<li><strong>-</strong> might be dropped at some point?</li>
</ul>

<a name="aboutCheckingClientJavascript"></a><strong>*</strong> A trick is applied to check if client has enabled Javascript when editor is integrated via Python: the complete instantiation code is written via <code>document.write(..)</code> (in Javascript) and a <code>&lt;noscript&gt;</code> tag is used to fall back on a regular <code>&lt;textarea&gt;</code>.

<h2><a name="3.">APIs</a></h2>

<h3><a name="3.1">Basic Integration</a></h3>

<p>To integrate the FCKeditor, please exclusively use the following method:</p>
<pre>
from htmlutils import get_html_text_editor
[...]
out += get_html_text_editor('myeditor')
</pre>

<p>Refer to <code>htmlutils.py</code> for more information about the
function and its parameters.</p>

<p>It is wise to always use the above method and never directly rely
on any FCKeditor file. You have to expect that the editor is not
always installed on the server, or that the client might not support
it (eg. Javascript disabled). In these cases, a basic
<code>&lt;textarea/&gt;</code> is used instead.<br/>
If you need to know what type of input form (<code>textarea</code> or
FCKeditor) was used by the client, you can catch the value of the form
variable <code>editor_type</code>, which is submitted at the same time
as other elements of your form.</p>

<h3><a name="3.2">File Upload Support</a></h3>

<p>In order to support file upload rigth from FCKeditor, you must call
 <code>get_html_text_editor(..)</code> with its <code>file_upload_url</code>
 parameter set to the URL to which the file will be uploaded.</p>

<p>The second step is to implement the URL handler
<code>file_upload_url</code> so that that it understands the
"commands" sent by FCKeditor, does something with the file (eg. moves
it to a chosen location) and sends a correct reply.</p>


<p>To do so, the easiest is to instantiate an
<code>FCKeditorConnectorInvenio</code> object with the input
parameters, and sends back the value returned by its
<code>doResponse()</code> function. Note that you have to correctly
set the response headers by reading the object <code>headers</code>
member and <strong>implement yourself restrictions checking in your
code</strong>, as this is not managed by the FCKeditorConnectorInvenio
class </p>


<p>You can use the following parameters when instantiating the connector:


<dl>
<dt><strong><code>user_files_absolute_path</code></strong></dt>
<dd>the base path where the files should be
saved. Eg:<code>%(CFG_PREFIX)s/var/data/comments/%(recid)s/%(uid)s</code></dd>

<dt><strong><code>user_files_path</code></strong></dt>
<dd>the base URL where the files can be accessed from the web, if
<code>user_files_absolute_path</code> is not a web accessible
folder. Eg:
<code>%(CFG_SITE_URL)s/record/%(recid)i/comments/attachments/get/%(uid)s</code></dd>
</dl>
</p>

<p>Note that if you set <code>user_files_path</code>, you have to
implement your own handler to stream the files from the directory
<code>user_files_absolute_path</code>. <br/>

Also note that whatever value you choose for the above parameters,
FCKeditor appends <em>sub-paths</em> automatically, such as
<code>/file/</code> for regular files, or <code>/image/</code> for
images.</p>

<p>Check
<code>cds-invenio/modules/webcomment/webcomment_webinterface::WebInterfaceCommentsFiles</code>
 URL handler to see how it works</p>

<p><em>There is currently no implementation for server files browsing.</em></p>